Creation of a project

Creating a project is done through two steps in "Create Project" section, see the following image:

That's all !

You can now check that a folder as indeed been created with the proper pathways:

You can see that folders have been created:

• 0_pecc_project: a folder containing metadata for peccary. It's actually the only folder that you cannot touch. Do not modify it
• 1_Data: a folder made in order to store your data files. It contains subfolders that you can change as you want.
• 2_Analysis: a folder made in order to store analysis files. It contains subfolders that you can change as you want.
• 3_Models: a folder made in order to store runs.

Note This default architecture corresponds to the original Peccary author ways of working. It can be modified in the future. Only the "0_pecc_project" subfolder really matters and must remain unchanged. All the other folders can be deleted or modified.

Loading a project

Loading a project is the first thing you will generally do when launching the shiny App. For that, you just have to enter the pathways of your project on "Path to Project File" and click on "load project".

That's all ! Now, every time Peccary would propose you to "store" elements, it will store these elements inside the project meta-file.

Peccary also store the pathways of previously opened project to have a quicker access to them when opening the shiny App. Only project created with the same computer ID (output of as.list(Sys.info())$user) will be displayed in the "Previous Project" select input. Last run opened by the user is automatically display when opening the Shiny App. Hence, if you just want to reopen last project you worked on, just launch the app and click on "Load project" (you always need to click on this button as the final step, even after selecting a project in "Previous project").

Add a dataset

To add a dataset, go in "Pre-modelisation" -> "Datasets" item, then follow the three following steps:

Regarding step 2, Peccary automatically tries go guess separator and decimals. After doing that, you will normally see the table containing all the datasets you have so far. In particular each dataset has a number and a file name. They will be used as identifiers. On the left panel, in "Preloaded dataset" selectInput box, the new dataset is now available.

Then you can modify some elements manually if you want. For instance, it might be useful to comment, to store a description of the model, or saving which columns is X (time) and Y (observation) (if not already guessed by Peccary). This X and Y value will be automatically loaded when selecting a dataset. This dataset selection is done with the "Preloaded dataset" select input in the left-side panel. Switching from one dataset to another take one second!

If you are working with a project, do not forget to save it so when relaunching the app, you will not have to do that again.

In the above image, you can also choose, when you will open the project, which dataset has to be load in "Preloaded dataset" item.

(Not mandatory) Add more information (header) to a dataset

Note: this is mainly experimental for now... No need to do it if it is the first time you use Peccary.

At the bottom of the page, you can select a dataset through it numbers, and then fill some information. It might notably be interesting to fill information regarding headers: what are the columns of ID, TIME, MDV, EVID.... Click to "Import", it will update the main table. If you are okay with it and working with a project, do not forget to save modifications.

Visualize your dataset

To visualize your dataset and obtain population statistics, move to "Dataset explo" item. You should obtain the following:

Modify your dataset

If you want to do some modification on your dataset, several input allow you to modify the dataset:

Two filters: First, there are two filters, using R syntax (& for and, | for or, == for equal, >, <, >=, <=...)

1. on left panel (black background), the filter will apply in others actions.
2. the "Exploratory filter" above will apply only on this "Graphical exploration" section.

Free manipulation: Secondly, you can perform free manipulation to add column or anything else. Here, temp represents the dataset after the filters have been applied. Last line of this free manipulation block must return the modify dataset.

Covariate extraction: A specific covariate extraction function exists, keeping only one row per "Extraction by" columns, and only columns having one value by this combination are kept. See here for more detail

Saving modification

Modification of the dataset would be by default only effective on the "Dataset explo" section, not on the other. To make them effective on other section (plot, NCA...), you need first to save a copy of this dataset. They are two ways of doing so, 1) by only saving the modifying code, 2) by creating a new file with modified dataset

Storing modifying code

By clicking on "Store modif" button, the modified dataset became available in the "Preloaded dataset" and in the summary of all available dataset. The mention "+ code" is added to the name of the original dataset. Don't forget to save the dataset table if you want to re-have access to this modified dataset when you reopen the Shiny App. In this dataset table, a column "codeToEval" shows exactly the code that is evaluated each time to select this dataset.

Create a new file

If you want to save the modification is a file, use the button "Create file with modif". The file is saved in the same folder as the original dataset. Name of the file is the same as the original plus *_peccModifX* with X being empty the first time a modification is save, and a number for the following. Here also, the dataset table is updated, but need to be saved if you want to automatically be able to load the file reopening the Shiny App. For traceability, modification and source dataset are presented in the "codeToEval" column (even though the code is not evaluated as they have already been applied in the saved dataset).

Covariate extraction

Before doing some statistical analysis, you need to have only one line per patient. One way to do so is to use the "Extract cov by" input and then press "Go". The table will be updated to keep one line per patient. Only columns with one unique value per patient will be kept, all the others are removed. {#covariateextraction}

Auto Population description (table1)

There is two ways to create a table1, the first one providing quick access to covariate description without the need to previously reduce the dataset. To do so:

And you can find the corresponding code just below:

Precise Population description (table1)

If you want more precise control on which covariate are continuous vs categorical, you need first to manually extract covariate (see "Covariate extraction " section above) to update the possible rows names in the Shiny app now ending with "_cat" and/or "_cont". That way you can choose if you want to consider a numeric covariate as categorical or as continuous.

Boolean counting

In this specific case, we have a boolean (True/False ; 0/1) column, for instance representing the occurrence of a side effect, and we want to count them with covariate stratification.

In this example, we then know than 3 out of 12 patients had a side effect. All of them have "> 3.5 & < 4.8" doseCAT covariate value (3/6).

Here, the Peccary code producing this output is available directly on the shiny App (this function has not been metaprogrammed yet).

Covariate plots

A recent function allows to have a quick plot visualization of one or two covariates. R code is also provided. More parameters will be available in the future (notably the choice of the statistical test). The printed code can peccary dependent but the Peccary independant code can be seen by adding "outputExpr = T" to the function.

Saving and loading analysis

If you are working with a project, you can store metadata of your analysis. Just enter a name and click on "save" button to save or update the analysis with that name.

To load, just choose the analysis you want and click on load -> all the fields are refilled!

First plot

Many fields directly correspond to classic ggplot syntax:

• col to colorize
• wrap to split the dataset in several subplots
• wrapscale allow you to choose whether you want each subplot having its own scale or if you want the same scale for everyone
• grid add an other dimension
• ID correspond to the "group" ggplot syntax (how to gather points in lines)
• point alpha and line alpha correspond to transparency of point and line
• xlog and ylog to have logarithmic axis
• Title, subtitle, xlabs, ylabs and caption adds to modify legends
• Size text speaks for itself
• ...

just explore! In the "More control" panel you can modify the labels, the color....

Some additional contents can be done, for instance:

• remove NA automatically remove NA from your dataset. Can modify line behavior
• standardization allow to divide every observation by a specific column (dose for instance)
• median computes median profiles (not really used for now, can be improved if needed)
• you can add line with the proper table

Special wrap with other patients in background

When wrapping it's often hard to compare a patient profile with all the others. To solve this issue, you can check the "grey all" checkbock to add all the other profiles in background. You can modify the transparency of these new lines with "bckgd_alpha".

The two filters system

There are two different filters:

1. the first one, on the left border, for "persistent filter", generally used for filter like "YTYPE == X" or to remove patients that we are not interested with.
2. the second filter is mostly used for "quick filtering", for instance if you want to quickly look at one specific patient for just one short moment.

In most case you can use one filter or the other without changing the output. However, it does have an important impact when using "grey_all" option. In fact, Peccary stores a temporary dataset for the background. The first filter is applied before storing this dataset, while the second filter is done after. In the following example, applying an ID filter on the first filter give a plot with 2 ID in the background, while on the second filter we have all ID in the background, but only two with highlighted data.

The R code sections on the figure above are found at the very bottom of the Shiny App page, where you can find the code producing your plot. Here you see how each filter is applied.

You can of course use both filters at the same time.

Peccary dependent and independent code

In the R code section, you have access to both Peccary dependent independent code. You can check the output by looking at the R code produced by peccary as an intermediate between your input and the output. You can use this code also for manual adjustments of the plot or to insert the graph in a report with free source code.

Saving / Loading a plot

To save, just give a name to a plot and click to save. The table of available plot is then updated.

Then to load a save, just click on the "Load" column at the proper plot.

You can also use the second column "pdf" to check plots you want to have in a pdf, then click on "Pdf export" (probably broken by now as I almost never used it after all...).

First model & simulations

To write, load or use a model, go to "Model building section".

Write the model

You can directly write a model in the appropriate section, as following:

And click on "Load Model".

Few rules regarding the syntax:

• it's a deSolve syntax, meaning a compartment X is created with "dX"
• use "<-" and not "=" (might change in the future)
• use ** and not ^ for power (might change in the future)
• you can add a "_output" at the end of a name to say it's an output of the model (not mandatory)
• you can add a "_plot" at the end of a name if you want to be able to plot it (not required for compartment and outputs)
• you can add the initial values of a compartment with, for instance "dGut_0 <- X". Generally, you do not need to do that (you will modify initial values after), excepted if you want a baseline parameter.

Note: as alternatives you can either use a library or load a model from Monolix, NONMEM or nlmixr files, see appropriate sections.

Fill inputs

When you click on "Load model", input data frames are updated, you just have to fill them now

You have:

• compartment with Name and values à t0. Note this value can be a formula (for instance "kin/kout") related to parameters
• parameters with name, values, distributions. Last column is useless for simulations, it represents whether the parameter is estimated, fixed or if it's in fact a covariate (input) from the dataset.
• administration protocol: based on events deSolve system: you add in compartment "Var" at time "time" the value "value". "Method"" is per default "add"", you can also reset a compartment by multiplying it by 0. Here you can also add tlag or bioavailability parameters, and handle perfusions.
• variance-covariance matrix: you must specify then if it's coded in standard deviation or in variance. You can remove the matrix to have a linear variance representation.
• output not required at this stage

Simulations

Now choose "Plot & Simulations", fill what you want to display, and click on "load plot" to create the plot.

Note: new versions of Peccary let you choose the ODE solver, between deSolve and RxODE !

Try several parameter values

To try several parameter values at once, just provide a R code returning an atomic vector of number.

Then you can choose how you want to display results with the "wrap" input.

Try several administration protocols

To test several administration protocols, just create a new protocol with a new number. Note that in "time" AND "Proto" column you can write R code which should return atomic numeric vectors.

Then with "wrap" column you can change how you want the output/

If you want to add different points on top of each protocol plot, you need to use the filterPlot column, associated to each protocol. Here is an example of a tumor growth inhibition model where each plot represents a different dose level with appropriate observations:

Simulation code

you can show the intermediate Peccary-independent code creating the simulation plot.

Saving

You can of course save and load a model.

Quick parameter estimation (prototype)

Peccary can perform a quick parameter estimation based on naive pool method. Only parameter with "Estimation" status will be optimized (step1). Then just click on "try-estimation" (step2). A very simple residuals optimization is performed based on the observation plotted (should be improved, this is just a quick but operational prototype). At the end of the estimation (200 iterations max, you may repeat the operation several time to improve the estimation), computed values are integrated in the parameter table and the curve are reprinted accordingly. Here is an example applied on a tumor growth inhibition model, with a control group and two dose levels (see previous section).

Importing NONMEM / Monolilx / nlmixr model inside Peccary

You can import Nonmem, monolix or nlmixr model data inside Peccary.

To do so, give the pathway of either a mlxtran file, a .res NONMEM file or nlmixr result object, and click on launch.

Then you see that everything is automatically filled! You can then switch from population values to individual patients one, and you can also change the administration protocol for the right patient!

You can also click on "use imported data" if you want, in your simulation use the dataset used for the model instead of the dataset used inside graphical exploration of Peccary. Doing so, only point regarding the selected patient will be displayed (or all of them in case of Population requirement). The column YTYPE allow you to select the right observation for the right curve.

With that system, Peccary will recreates the prediction of any patient, you can then try to modify some values or the structural equation to see how to improve any individual fits!

QSP modeling importation

If you want to build a QSP model with many equations and fixed values, Peccary offer a simple way to do it. First create a csv file which should contain the following columns

• Entity: either one compounds name ( X_Y means "complex of X and Y gathered"), either an equation.
• init_value , if you want to have a initial value different from 0. Can be a parameter name.
• kdeg: degradation rate of compounds
• kforward and kbackward: for complexes or reversible transformation/equations
• k: rate for non-reversible transformation/equation
• kprod: production rate of a compounds
• order_kprod: either 0 (linear) or 1 (proportional)

Then just provide the path of that csv on the shiny app and click on launch model: Peccary will translate the csv file in a fully functionally ODE systems of equations!

What about models’ library?

A prototype of library system is proposed. Works well but only few models are available, need to complete it first.

What about covariates?

Sometimes you may want to add covariate to a model without modifying the core model. This is possible thanks to the "Opti. covariate equations" system.

Then you can toggle "use covariate" if you want to work with covariate (NONMEM system) or works only with the structural model (Monolix system).

Tlag, bioavailability and perfusion

Tlag and bioavailability work the same way, you have to check for every administration line if you want to add a tlag or a bioavailability. A new parameter will then automatically be added in the parameter table. If you want one of these parameters being the same for several administration rows, just use the same ADM columns for concerned rows.

Here is an example with tlag (delaying the time of administration)

And an example with bioavailability (directly modifying the injected doses inside the system).

For perfusion, you need to mention first if you want to code it in rate or in time duration, then give the concerned number (rate or time) in the "Perf_num" column.

First design evaluation

First, you need to create your model and fill initial table.

Here it is important, for each parameter, to choose whether the parameter is Estimated, Fixed or if is actually not a parameter but an input from de dataset.

Regarding matrix, for the moment only the variance work with PopEd, the covariance has to been integrated yet. If you want to fix a parameter, just write an "F" after the value of the variance.

Then, on "Optimal Design", you have the table containing:

• Output: variable that is measured
• Group: number of the group
• Proto: each group has a protocol, linked to the administration protocol table
• TimeSample: R code returning the vector of time observation
• add: additive error for this Output. Add an "F" to say it is fixed
• prop: proportional error for this output. add an "F" so say it is fixed
• nidgroup: size of the group delete: check this line and then click on "Delete line" to remove it cov: adding a covariate, see next chapter.

Then click on "eval" design and below you will find the plot and results.

The implementation is quite new and has not been used many times. Be careful, look at the produced code before integrating results in your work.

The rebuilt Poped code is provided in the code section. If you want to perform optimal design, just copy this code in a R script and do the appropriate modification to transform design evaluation into optimal design!

Adding groups (and covariates)

To add a new group, just click on "Add line" , and change the number of the group. Each group can have its own TimeSample per Output, size (nidgroup) but also protocol administration and covariate. In this example Group1 has a clearance of 15, Group2 of 10. This is how you can handle categorical covariate.

Note that if for the same output two groups cannot have different add or prop error. Not used values will be erased.

Adding a second YTYPE

If you have several outputs, just modify the first column "Output".

In the below example, note the empty "Proto" and "nidgroup" case: these values cannot be duplicated for the same group, and will thus be automatically be erased by Peccary.

Peccary -> Nlmixr

Just click on Generate code. For the moment does not work if you have several outputs.

By clicking on "estimate"", you evaluate the code above and so trigger the parameter estimation

Peccary -> Monolix

For the moment do not play with anything excepted the "Launch ode translation". The rest is more complex, work probably only on my computer, and need some adjustments.

Do not click on red crosses (old and not maintained function, probable crash if used)

Peccary -> NONMEM

For nonmem just click on "Launch ode translation". The baseline parameters will be removed.

You can choose if you want a mu-reference or not, and you can choose if you want the blq handling block.

Do not click on red crosses (old and not maintained function, probable crash if used)

Load runs

To find run(s), simply copy/past the path to a folder containing some runs, the click on go.

Note: The console equivalent is: > demo <- createFolder("yourpath")

You can use "subpath" to navigate through subfolders.

See run results

Each run has its own number. To see results of a run, just write this number on left panel:

You can also compare runs by just writing several numbers in the "Runs" input. For instance

• "1 3" to analyze run 1 and 3
• "1:4" to analyze run 1 to 4
• "1:4 - 3" to analyze run 1 to 4 excepted 3.

Note: the console equivalent is:

results(demo(c(1,2,4)))

Individual Prediction

On the left panel the "Run" input is general and will be copied in every "Run" subfunction. A first plot will be produced but then you will have to click on "Update Plot" to take into account modifications.

Here are the main input:

• n: per default, you do not have every patients: Peccary randomly take 20 patients to display them. You can change this number. It is useless if an ID filter is activated
• ylog: for having logarithmic scale on Y axis
• xlog: for having logarithmic scale on x Axis
• Free scale: if all patient should share the same axis or not
• Filter: a free filter applied, use ID, PRED, IPRED, OBS...
• low limit: useful in logarithmic scale to avoid having values at \(10^{-23}\)
• upper limit: same thing (much less used)
• extr. value: write what is the lowest (or highest) values removed by "low limit" and "high limit" parameter.
• interactive figure: to use ggplotly.

GOF

Per default, in "Single static" mode, you just create GOF for the first run number (here run number 1).

Let's imagine you want now only "oBSvsPRED" and "OBSvsIPRED" for each run. Do the following:

• in selectGOF, chose the number of the type of plot you want (here 1 = "OBSvsPRED" and 2 = "OBSvsIPRED")
• click on multiple static

There is the a more formal and generic way to proceed, allowing to compare several runs and several covariate value as you want. When you add several runs or a covariate, you will see at the end of the page a table that contains every subplot Peccary will do when clicking on "multiple static". This can quickly escalate to a too high number of plot (hence the absence of automatic creation). You can then use the "Filter table below" input to filter the table, and one it has the size/subplot you want, then click on "multiple static".

Covariate analysis

Covariate analyses is intuitive. Giving a categorical covariate and multiple runs, one can easily compare the distribution between runs.

Variance covariance matrix

Variance covariance matrix is also intuitive. It contains the same subplot systems than the GOF section. By default, only the result of the first run will be displayed:

Below, a table give you all the subplot peccary is able to perform. You can then filter what you want to reduce the table before clicking "Multiple run" to display them. One can them very easily compare a specific subplot between several runs!

Individual Likelihood

To compare ILL between two runs and see if there is a covariate asymmetry, do the following

Note do not use the next sections (sensitivity, VPC, plt saved )

Quick overview report or runs

Peccary is able to provide quick overview reports on runs. Simply write the number of the runs you want in you report and click on AllPlots.

After few seconds or minutes depending on the number and complexity of the runs, a pdf will open with:

• one comparative run values table (if several run inputted)
• one page per run with detailed results, prediction, GOF, covariate analyses, variance/covariance matrix...
• one final page comparing run estimations.